<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="Cask Data, Inc." name="author" />
<meta content="HTTP RESTful Interface to the Cask Data Application Platform" name="description" />
<meta content="Copyright © 2014-2017 Cask Data, Inc." name="copyright" />


    <meta name="git_release" content="6.1.1">
    <meta name="git_hash" content="05fbac36f9f7aadeb44f5728cea35136dbc243e5">
    <meta name="git_timestamp" content="2020-02-09 08:22:47 +0800">
    <title>Dataset HTTP RESTful API</title>

    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-dynamicscrollspy-4.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/abixTreeList-2.css" type="text/css" />
    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '6.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>

    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="Cask Data Application Platform 6.1.1 Documentation" href="../index.html" />
    <link rel="up" title="CDAP HTTP RESTful API v3" href="index.html" />
    <link rel="next" title="Lifecycle HTTP RESTful API" href="lifecycle.html" />
    <link rel="prev" title="Configuration HTTP RESTful API" href="configuration.html" />
    <!-- block extrahead -->
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <!-- block extrahead end -->

</head>
<body role="document">

<!-- block navbar -->
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
    <div class="container-fluid">
      <div class="row">
        <div class="navbar-header">
          <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
          <a class="navbar-brand" href="../table-of-contents/../../index.html">
            <span><img alt="CDAP logo" src="../_static/cdap_logo.svg"/></span>
          </a>

          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>

          <div class="pull-right">
            <div class="dropdown version-dropdown">
              <a href="#" class="dropdown-toggle" data-toggle="dropdown"
                role="button" aria-haspopup="true" aria-expanded="false">
                v 6.1.1 <span class="caret"></span>
              </a>
              <ul class="dropdown-menu">
                <li><a href="//docs.cdap.io/cdap/5.1.2/en/index.html">v 5.1.2</a></li>
                <li><a href="//docs.cdap.io/cdap/4.3.4/en/index.html">v 4.3.4</a></li>
              </ul>
            </div>
          </div>
          <form class="navbar-form navbar-right navbar-search" action="../search.html" method="get">
            <div class="form-group">
              <div class="navbar-search-image material-icons"></div>
              <input type="text" name="q" class="form-control" placeholder="  Search" />
            </div>
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>

          <div class="collapse navbar-collapse nav-collapse navbar-right navbar-navigation">
            <ul class="nav navbar-nav"><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../index.html">简介</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../guides.html">手册</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link current" href="../table-of-contents/../../reference-manual/index.html">参考</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../faqs/index.html">帮助</a></li>
            </ul>
          </div>

        </div>
      </div>
    </div>
  </div><!-- block navbar end -->
<!-- block main content -->
<div class="main-container container">
  <div class="row"><div class="col-md-2">
      <div id="sidebar" class="bs-sidenav scrollable-y-outside" role="complementary">
<!-- theme_manual: reference-manual -->
<!-- theme_manual_highlight: reference -->
<!-- sidebar_title_link: Reference -->

  <div role="note" aria-label="manuals links"><h3>Reference</h3>
    <ul class="reference-page-menu">
      <nav class="pagenav">
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html"> Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../characters.html"> Supported Characters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cli-api.html"> Command Line Interface API</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html"> HTTP RESTful API</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="artifact.html">Artifact</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Dataset</a></li>
<li class="toctree-l2"><a class="reference internal" href="lifecycle.html">Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="metadata.html">Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="namespace.html">Namespace</a></li>
<li class="toctree-l2"><a class="reference internal" href="dashboard.html">Dashboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="preferences.html">Preferences</a></li>
<li class="toctree-l2"><a class="reference internal" href="profile.html">Profile</a></li>
<li class="toctree-l2"><a class="reference internal" href="query.html">Query</a></li>
<li class="toctree-l2"><a class="reference internal" href="reports.html">Reports</a></li>
<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="service.html">Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="transactions.html">Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Workflow</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../java-client-api.html"> Java Client API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../javadocs/index.html"> Javadocs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html"> 发行说明</a></li>
<li class="toctree-l1"><a class="reference internal" href="../licenses/index.html"> Trademarks, Licenses, and Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html"> 术语表</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html"> Index</a></li>
</ul>
</nav>
    </ul>
  </div></div>
    </div><div class="col-md-8 content" id="main-content">
    
  <div class="section" id="dataset-http-restful-api">
<span id="http-restful-api-dataset"></span><h1>Dataset HTTP RESTful API<a class="headerlink" href="#dataset-http-restful-api" title="Permalink to this headline">🔗</a></h1>
<p>The CDAP Dataset HTTP RESTful API allows you to interact with datasets through HTTP. You
can list, create, delete, and truncate datasets. For details on datasets, see the
<a class="reference external" href="../../../developer-manual/building-blocks/datasets/index.html#datasets-index" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">CDAP Components, datasets section</span></a></p>
<p>All methods or endpoints described in this API have a base URL (typically
<code class="docutils literal notranslate"><span class="pre">http://&lt;host&gt;:11015</span></code> or <code class="docutils literal notranslate"><span class="pre">https://&lt;host&gt;:10443</span></code>) that precedes the resource
identifier, as described in the <a class="reference internal" href="introduction.html#http-restful-api-conventions-base-url"><span class="std std-ref">RESTful API Conventions</span></a>.
These methods return a status code, as listed in the <a class="reference internal" href="introduction.html#http-restful-api-status-codes"><span class="std std-ref">RESTful API  Status Codes</span></a>.</p>
<div class="section" id="listing-all-datasets">
<h2>Listing all Datasets<a class="headerlink" href="#listing-all-datasets" title="Permalink to this headline">🔗</a></h2>
<p>You can list all datasets in CDAP by issuing an HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/datasets</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The response body will contain a JSON-formatted list of the existing datasets:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
   <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;cdap.user.purchases&quot;</span><span class="p">,</span>
   <span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;io.cdap.cdap.api.dataset.lib.ObjectStore&quot;</span><span class="p">,</span>
   <span class="nt">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;Purchases Dataset&quot;</span><span class="p">,</span>
   <span class="nt">&quot;properties&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="nt">&quot;schema&quot;</span><span class="p">:</span><span class="s2">&quot;...&quot;</span><span class="p">,</span>
      <span class="nt">&quot;type&quot;</span><span class="p">:</span><span class="s2">&quot;...&quot;</span>
   <span class="p">},</span>
   <span class="nt">&quot;datasetSpecs&quot;</span><span class="p">:</span> <span class="p">{</span>
      <span class="c">...</span>
   <span class="p">}</span>
 <span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-a-dataset">
<span id="http-restful-api-dataset-creating"></span><h2>Creating a Dataset<a class="headerlink" href="#creating-a-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can create a dataset by issuing an HTTP PUT request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;</span>
</pre></div>
</div>
<p>with JSON-formatted name of the dataset type, properties, and description in a body:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
   <span class="nt">&quot;typeName&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;type-name&gt;&quot;</span><span class="p">,</span>
   <span class="nt">&quot;properties&quot;</span><span class="p">:{</span>
      <span class="nt">&quot;&lt;properties&gt;&quot;</span>
    <span class="p">},</span>
   <span class="nt">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;Dataset Description&quot;</span><span class="p">,</span>
   <span class="nt">&quot;principal&quot;</span><span class="p">:</span> <span class="s2">&quot;user/example.net@EXAMPLEKDC.NET&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Name of the new dataset</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">type-name</span></code></td>
<td>Type of the new dataset</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">properties</span></code></td>
<td>Dataset properties, map of String to String</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">description</span></code></td>
<td>Dataset description</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">principal</span></code> <em>(optional)</em></td>
<td>Kerberos principal with which the dataset should be created; once a dataset has
been created, this cannot be changed <em>(optional)</em></td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Requested dataset was successfully created</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">403</span> <span class="pre">Forbidden</span></code></td>
<td>The dataset already exist with a different Kerberos principal</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>Requested dataset type was not found</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code></td>
<td>Dataset with the same name already exists</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">PUT</span> <span class="pre">/v3/namespaces/default/data/datasets/mydataset</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Body</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;typeName&quot;:&quot;io.cdap.cdap.api.dataset.table.Table&quot;,</span></code> <code class="docutils literal notranslate"><span class="pre">&quot;properties&quot;:{&quot;dataset.table.ttl&quot;:&quot;3600&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;description&quot;:&quot;My</span> <span class="pre">Dataset</span> <span class="pre">Description&quot;,</span></code> <code class="docutils literal notranslate"><span class="pre">&quot;principal&quot;:&quot;user/example.net&#64;EXAMPLEKDC.NET&quot;}</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Creates a dataset named <em>mydataset</em> of the type <code class="docutils literal notranslate"><span class="pre">Table</span></code> in the namespace <em>default</em>
with the time-to-live property set to 1 hour, a description of <code class="docutils literal notranslate"><span class="pre">My</span> <span class="pre">Dataset</span> <span class="pre">Description</span></code>,
owned by the principal identified by <code class="docutils literal notranslate"><span class="pre">user/example.net&#64;EXAMPLEKDC.NET</span></code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="properties-of-an-existing-dataset">
<span id="http-restful-api-dataset-properties"></span><h2>Properties of an Existing Dataset<a class="headerlink" href="#properties-of-an-existing-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve the properties with which a dataset was created or last updated by issuing an HTTP GET request to
the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;/properties</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Name of the existing dataset</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Requested dataset was successfully updated</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>Requested dataset instance was not found</td>
</tr>
</tbody>
</table>
<p>The response—if successful—will contain the JSON-formatted properties:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
   <span class="nt">&quot;key1&quot;</span><span class="p">:</span><span class="s2">&quot;value1&quot;</span><span class="p">,</span>
   <span class="nt">&quot;key2&quot;</span><span class="p">:</span><span class="s2">&quot;value2&quot;</span><span class="p">,</span>
   <span class="c">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Note that this will return the original properties that were submitted when the dataset was created or updated.
You can use these properties to create a clone of the dataset, or as a basis for updating some properties of this
dataset without modifying the remaining properties.</p>
</div>
<div class="section" id="metadata-of-an-existing-dataset">
<span id="http-restful-api-dataset-meta"></span><h2>Metadata of an Existing Dataset<a class="headerlink" href="#metadata-of-an-existing-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve the metadata with which a dataset was created by issuing an HTTP GET
request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Name of the existing dataset</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Metadata for the requested dataset instance was successfully returned</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>Requested dataset instance was not found</td>
</tr>
</tbody>
</table>
<p>The response body will contain JSON-formatted metadata of the existing dataset:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="nt">&quot;spec&quot;</span><span class="p">:</span> <span class="p">{</span>
    <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;ownedDataset&quot;</span><span class="p">,</span>
    <span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;datasetType1&quot;</span><span class="p">,</span>
    <span class="nt">&quot;originalProperties&quot;</span><span class="p">:</span> <span class="p">{},</span>
    <span class="nt">&quot;properties&quot;</span><span class="p">:</span> <span class="p">{},</span>
    <span class="nt">&quot;datasetSpecs&quot;</span><span class="p">:</span> <span class="p">{}</span>
  <span class="p">},</span>
  <span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="p">{</span>
    <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;datasetType1&quot;</span><span class="p">,</span>
    <span class="nt">&quot;modules&quot;</span><span class="p">:</span> <span class="p">[</span>
      <span class="p">{</span>
        <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;module1&quot;</span><span class="p">,</span>
        <span class="nt">&quot;className&quot;</span><span class="p">:</span> <span class="s2">&quot;io.cdap.cdap.data2.datafabric.dataset.service.TestModule1&quot;</span><span class="p">,</span>
        <span class="nt">&quot;jarLocationPath&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/data/module1/archive/module1.jar&quot;</span><span class="p">,</span>
        <span class="nt">&quot;types&quot;</span><span class="p">:</span> <span class="p">[</span>
          <span class="s2">&quot;datasetType1&quot;</span>
        <span class="p">],</span>
        <span class="nt">&quot;usesModules&quot;</span><span class="p">:</span> <span class="p">[],</span>
        <span class="nt">&quot;usedByModules&quot;</span><span class="p">:</span> <span class="p">[]</span>
      <span class="p">}</span>
    <span class="p">]</span>
  <span class="p">},</span>
  <span class="nt">&quot;principal&quot;</span><span class="p">:</span> <span class="s2">&quot;user/example.net@EXAMPLEKDC.NET&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="updating-an-existing-dataset">
<span id="http-restful-api-dataset-updating"></span><h2>Updating an Existing Dataset<a class="headerlink" href="#updating-an-existing-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can update an existing dataset’s table and properties by issuing an HTTP PUT request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;/properties</span>
</pre></div>
</div>
<p>with JSON-formatted properties in the body:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
   <span class="nt">&quot;key1&quot;</span><span class="p">:</span><span class="s2">&quot;value1&quot;</span><span class="p">,</span>
   <span class="nt">&quot;key2&quot;</span><span class="p">:</span><span class="s2">&quot;value2&quot;</span><span class="p">,</span>
   <span class="c">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p><strong>Notes:</strong></p>
<ul class="simple">
<li>The dataset must already exist.</li>
<li>The properties given in this request replace all existing properties; that is, if you
have set other properties for this table, such as time-to-live (<code class="docutils literal notranslate"><span class="pre">dataset.table.ttl</span></code>),
you must also include those properties in the update request.</li>
<li>You can retrieve the existing properties using the <a class="reference internal" href="#http-restful-api-dataset-properties"><span class="std std-ref">Properties of an Existing Dataset</span></a>
and use that as the basis for constructing your request.</li>
<li>Once a dataset has been created, the <code class="docutils literal notranslate"><span class="pre">principal</span></code> cannot be changed.</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Name of the existing dataset</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Requested dataset was successfully updated</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>Requested dataset instance was not found</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">PUT</span> <span class="pre">/v3/namespaces/default/data/datasets/mydataset/properties</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Body</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;dataset.table.ttl&quot;:&quot;7200&quot;}</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>For the <em>mydataset</em> of type <code class="docutils literal notranslate"><span class="pre">Table</span></code> of the namespace <em>default</em>, update the dataset
and its time-to-live property to 2 hours</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="deleting-a-dataset">
<h2>Deleting a Dataset<a class="headerlink" href="#deleting-a-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can delete a dataset by issuing an HTTP DELETE request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Dataset name</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Dataset was successfully deleted</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>Dataset named <em>dataset-name</em> could not be found</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">DELETE</span> <span class="pre">/v3/namespaces/default/data/datasets/mydataset</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Deletes the dataset <em>mydataset</em> in the namespace <em>default</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="deleting-all-datasets">
<span id="http-restful-api-dataset-deleting-all"></span><h2>Deleting all Datasets<a class="headerlink" href="#deleting-all-datasets" title="Permalink to this headline">🔗</a></h2>
<p>If the property <code class="docutils literal notranslate"><span class="pre">enable.unrecoverable.reset</span></code> in <code class="docutils literal notranslate"><span class="pre">cdap-site.xml</span></code> is set to <code class="docutils literal notranslate"><span class="pre">true</span></code>,
you can delete all Datasets (in a namespace) by issuing an HTTP DELETE request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/unrecoverable/namespaces/&lt;namespace-id&gt;/datasets</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>All Datasets were successfully deleted</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">403</span> <span class="pre">Forbidden</span></code></td>
<td>Property to enable unrecoverable methods is not enabled</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code></td>
<td>Programs are currently running in the namespace</td>
</tr>
</tbody>
</table>
<p>This command will only work if all programs in the namespace are not running.</p>
<p>If the property <code class="docutils literal notranslate"><span class="pre">enable.unrecoverable.reset</span></code> in <code class="docutils literal notranslate"><span class="pre">cdap-site.xml</span></code> is not set to
<code class="docutils literal notranslate"><span class="pre">true</span></code>, this operation will return a Status Code <code class="docutils literal notranslate"><span class="pre">403</span> <span class="pre">Forbidden</span></code>. Note that this
operation can only be performed if all programs are stopped. If there’s at least one
program that is running, this operation will return a Status Code <code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code>.</p>
<p>This method must be exercised with extreme caution, as there is no recovery from it.</p>
</div>
<div class="section" id="truncating-a-dataset">
<h2>Truncating a Dataset<a class="headerlink" href="#truncating-a-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can truncate a dataset by issuing an HTTP POST request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-name&gt;/admin/truncate</span>
</pre></div>
</div>
<p>This will clear the existing data from the dataset. This cannot be undone.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Dataset name</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Dataset was successfully truncated</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="datasets-used-by-an-application">
<h2>Datasets used by an Application<a class="headerlink" href="#datasets-used-by-an-application" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve a list of datasets used by an application by issuing a HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/datasets</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Application ID</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Request was successful</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="datasets-used-by-a-program">
<h2>Datasets used by a Program<a class="headerlink" href="#datasets-used-by-a-program" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve a list of datasets used by a program by issuing a HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/datasets</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Application ID</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>Program type, one of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Program ID</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Request was successful</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="programs-using-a-dataset">
<h2>Programs using a Dataset<a class="headerlink" href="#programs-using-a-dataset" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve a list of programs that are using a dataset by issuing a HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/datasets/&lt;dataset-id&gt;/programs</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-id</span></code></td>
<td>Dataset ID</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Request was successful</td>
</tr>
</tbody>
</table>
</div>
</div>

</div>
    <div class="col-md-2">
      <div id="right-sidebar" class="bs-sidenav scrollable-y" role="complementary">
        <div id="localtoc-scrollspy">
        </div>
      </div>
    </div></div>
</div>
<!-- block main content end -->
<!-- block footer -->
<footer class="footer">
      <div class="container">
        <div class="row">
          <div class="col-md-2 footer-left"><a title="Configuration HTTP RESTful API" href="configuration.html" />Previous</a></div>
          <div class="col-md-8 footer-center"><a class="footer-tab-link" href="../table-of-contents/../../reference-manual/licenses/index.html">Copyright</a> &copy; 2014-2020 Cask Data, Inc.&bull; <a class="footer-tab-link" href="//docs.cask.co/cdap/6.1.1/cdap-docs-6.1.1-web.zip" rel="nofollow">Download</a> an archive or
<a class="footer-tab-link" href="//docs.cask.co/cdap">switch the version</a> of the documentation
          </div>
          <div class="col-md-2 footer-right"><a title="Lifecycle HTTP RESTful API" href="lifecycle.html" />Next</a></div>
        </div>
      </div>
    </footer>
<!-- block footer end -->
<script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script><script type="text/javascript" src="../_static/js/bootstrap-sphinx.js"></script><script type="text/javascript" src="../_static/js/abixTreeList-2.js"></script><script type="text/javascript" src="../_static/js/cdap-dynamicscrollspy-4.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script><script type="text/javascript" src="../_static/js/copy-to-clipboard.js"></script><script type="text/javascript" src="../_static/js/jquery.mousewheel.min.js"></script><script type="text/javascript" src="../_static/js/jquery.mCustomScrollbar.js"></script><script type="text/javascript" src="../_static/js/js.cookie.js"></script><script type="text/javascript" src="../_static/js/tabbed-parsed-literal-0.2.js"></script><script type="text/javascript" src="../_static/js/cdap-onload-javascript.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script>
    <script src="https://cdap.gitee.io/docs/cdap/json-versions.js"/></script>
  </body>
</html>